﻿// ===============================================================================
// IMarkupCache.cs
// EOS Web Framework
// ===============================================================================
// Copyright (c) EOS Development Group. All rights reserved.
// ===============================================================================

namespace EOS.Framework.Web.Mvc
{
    using System;

    /// <summary>
    /// Caches loading of markup files.
    /// </summary>
    public interface IMarkupCache
    {
        /// <summary>
        /// Create a markup object from a markup, which is already loaded and has the given name,
        /// </summary>
        /// <param name="name">The name of the markup, which should be loaded. Cannot be null or empty.</param>
        /// <returns>The loaded markup.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is null (Nothing in Visual Basic).</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is a string of length 0.</exception>
        /// <exception cref="MarkupNotFoundException">A markup with the given name does not exist.</exception>
        IMarkup CreateMarkup(string name);

        /// <summary>
        /// Create a markup object by the given name.
        /// </summary>
        /// <param name="markup">The markup, where the object will be created from.</param>
        /// <param name="name">The name of the markup, which should be loaded. Cannot be null or empty.</param>
        /// <returns>The loaded markup.</returns>
        /// <exception cref="ArgumentNullException">
        /// 	<para><paramref name="markup"/> is null (Nothing in Visual Basic).</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="name"/> is null (Nothing in Visual Basic).</para>
        /// </exception>
        /// <exception cref="ArgumentException">
        /// 	<para><paramref name="markup"/> is a string of length 0.</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="name"/> is a string of length 0.</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="name"/> is no valid xml.</para>
        /// </exception>
        IMarkup CreateMarkup(string markup, string name);

        /// <summary>
        /// Loads the markup from a file.
        /// </summary>
        /// <param name="path">The path of the file.</param>
        /// <param name="name">The name of the markup, which should be loaded. Cannot be null or empty.</param>
        /// <returns>The loaded markup.</returns>
        /// <exception cref="ArgumentNullException">
        /// 	<para><paramref name="path"/> is null (Nothing in Visual Basic).</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="name"/> is null (Nothing in Visual Basic).</para>
        /// </exception>
        /// <exception cref="ArgumentException">
        /// 	<para><paramref name="path"/> is a string of length 0 or contains only blanks.</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="name"/> is a string of length 0 or contains only blanks.</para>
        /// </exception>
        IMarkup LoadMarkupFromFile(string path, string name);

        /// <summary>
        /// Determines whether there is markup file in the cache with the given name.
        /// </summary>
        /// <param name="name">The name.</param>
        /// <returns>
        /// 	<c>true</c> if there is markup file in the cache with the given name; otherwise, <c>false</c>.
        /// </returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is null (Nothing in Visual Basic).</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is a string of length 0.</exception>
        bool HasInCache(string name);

        /// <summary>
        /// Clears the cache.
        /// </summary>
        void Clear();
    }
}
